NOMBRE¶

%man% - una interfaz de los manuales de referencia electrónicos

SINOPSIS¶

%man% [-c|-w|-tZT dispositivo] [-adhu7V] [-m sistema[,...]] [-L locale] [-p cadena] [-M ruta] [-P paginador] [-r prompt] [-S lista] [-e extension] [[sección] pagina ...] ...
%man% -l [-7] [-tZT dispositivo] [-p cadena] [-P paginador] [-r prompt] fichero ...
%man% -k [-M ruta] palabra_clave ...
%man% -f [-M ruta] pagina ...

DESCRIPCIÓN¶

%man% es el paginador del manual del sistema. Las páginas usadas como argumentos al ejecutar %man% suelen ser normalmente nombres de programas, útiles o funciones. La página de manual associada con cada uno de esos argumentos es buscada y presentada. Si la llamada da también la sección, %man% buscará sólo en dicha sección del manual. Normalmente, la búsqueda se lleva a cabo en todas las secciones de manual disponibles según un orden predeterminado, y sólo se presenta la primera página encontrada, incluso si esa página se encuentra en varias secciones.

La siguiente tabla muestra los números de sección del manual y los tipos de páginas que contienen.

Una página de manual tiene varias partes.

Éstas están etiquetadas como NOMBRE, SINOPSIS, DESCRIPCIÓN, OPCIONES, FICHEROS, VÉASE TAMBIÉN, BUGS, y AUTOR.

En la sección SINOPSIS se siguen los siguientes convenios que pueden servir de guía para otras secciones.

El ejemplo del empleo de la orden o función debe recogerá todos los posibles usos. En algunos casos es recomendable ilustrar algunos usos exclusivos como se puede ver en la SINOPSIS de esta página de manual.

EJEMPLOS¶

%man% ls

Presenta la página de manual del elemento (programa) ls.

%man% -a intro

Presenta, secuencialmente, todas las páginas de intro disponibles en el manual. Entre página y página se puede decidir saltar a la siguiente o salir del paginador completamente.

%man% -t alias | lpr -Pps

Formatea la página de manual referenciada por `alias', generalmente una página de manual de tipo shell, usando el formato predeterminado troff o groff y redirige la salida a la impresora llamada ps. La salida predeterminada de groff generalmente es PostScript. %man% --help debería informarle de que procesador está siendo usado con la opción -t

%man% -l -Tdvi ./foo.1x.gz > ./foo.1x.dvi

Esta orden descomprime y formatea el fichero fuente nroff de la página de manual ./foo.1x.gz y lo convierte en un fichero con formato independiente de dispositivo (dvi). Es necesario usar la redirección pues la opción -T dirige la salida al stdout sin paginador. La salida puede verse mediante un programa como xdvi o puede incluso convertirse al formato PostScript usando un programa como dvips.

%man% -k printf

Busca la palabra clave printf entre las descripciones breves y las páginas de manual y presenta todas las que casen.

%man% -f smail

Busca las páginas de manual referenciadas por smail e imprime la descripcion breve de las que encuentre.

DESCRIPCIÓN DETALLADA¶

Existen muchas opciones en %man% cuyo objeto es dar la mayor flexibilidad posible al usuario. Se puede cambiar la ruta, el orden de las secciones, el procesador de salida y otras propiedades y operaciones descritas a continuación.

Si se activan, varias variables de entorno son interrogadas para determinar el modo en que opera %man%. Se puede activar la variable `conjunta' $MANOPT asignándole cualquier cadena en formato de línea de órdenes con la excepción de que cualquier espacio en un argumento ha de ser precedido de `\'. %man% analizará $MANOPT antes de analizar su propia línea de órdenes. Aquellas opciones que tengan argumentos, se pueden cambiar si se incluyen al invocar man. Para desactivar todas las opciones activas en $MANOPT, basta usar -D como primera opción en la línea de órdenes. Esto hace que %man% `olvide' las opciones de $MANOPT aunque el contenido de la variable tiene que ser de todos modos el correcto.

Los útiles de páginas de manual incluidos en el paquete man-db hacen uso extenso de cachés índices de las bases de datos. Estos cachés contienen información sobre donde se encuentra cada una de las páginas del manual en el sistema de ficheros y lo que contiene el whatis (breve descripción de una línea de la página de manual). Uno de los cometidos de %man% es asegurarse de que los cachés son siempre consistentes. Las bases de datos caché permiten obviar el uso de software que actualice las bases de datos tipo texto whatis tradicionales, e incrementan la velocidad de ejecución de %man% si se compara con lo que tardaría si tuviese que buscar todo el sistema de ficheros cada vez que necesitase encontrar la página de manual adecuada.

Cuando %man% no encuentra un fichero índice de la base de datos creado por %mandb% para una jerarquía de páginas de manual dada, se efectuará una búsqueda pero será necesario usar expansión de caracteres comodín para buscar dentro de dicha jerarquía.

Si %whatis% o %apropos% no encuentran un fichero índice intentarán extraer la información de una base de datos whatis tradicional.

Estos útiles permiten el uso de ficheros fuente nroff comprimidos (con extensiones .Z, .z y .gz). Es posible utilizar cualquier extensión para las páginas comprimidas pero es necesario conocer esta información durante la compilación. También, de forma predeterminada, cualquier página cat generada, se comprime utilizando gzip. Cualquier jerarquía de páginas de manual `global' como /usr/man o /usr/X11R6/man puede utilizar cualquier directorio como raíz de su jerarquía de páginas cat. De forma tradicional, se acostumbra a almacenarlas bajo la misma jerarquía que las man, pero por razones del tipo de las mencionadas en el Estándar del Sistema de Ficheros Linux (FSSTND), puede ser más apropiado almacenarlas en otros lugares.

Si precisa más detalles de cómo se hace, por favor, refiérase a la página de manpath(5). Si lo que quiere es enteder las razones, refiérase al estándar.

Este paquete tiene sorporte internacional. Las páginas en lengua nativa pueden accederse (si se encuentran disponibles) mediante el uso de las funciones locale . Para usarlo, debe bien activar las variables $LC_MESSAGES, $LANG o cualquier variable de entorno del sistema asignándoles el valor correspondiente a su idioma, generalmente usando el formato especificado por el estándar POSIX 1003.1 :

<idioma>[_<territorio>[.<conjunto-de-caracteres>[,<versión>]]]

Si la página deseada esta disponible en sus informaciones locale, se presentará en vez de la página estándar (generalmente en inglés americano).

Este paquete también incorpora el soporte de catálogos de mensajes internacionales y es activado del mismo modo, siempre y cuando esté disponible. En el caso de que las páginas de manual y los catálogos de mensajes que acompañan este paquete no estén disponibles en su lengua nativa y si quisiese colaborar en su traducción, por favor póngase en contacto con el autor que actúa de coordinador.

Si necesita más información sobre otras características y extensiones disponibles con este paginador de manual, por favor refiérase a los documentos que se suministran con este paquete.

VALORES PREDETERMINADOS¶

%man% busca las páginas del manual deseadas en los índices bases de datos caché. Si la `busqueda' es infructuosa, se ejecuta una comprobación de la consistencia de la base de datos caché para asegurarse de que el caché refleja fielmente el sistema de ficheros. Generalmente no es necesario ejecutar %mandb% una vez que se ha creado el caché inicial salvo que este quede corrompido.

Una vez se localice una página de manual, se intenta determinar si existe una página relativa preformateada `cat' más reciente que el fichero nroff. En caso afirmativo, esta página (generalmente) se descomprime y se presenta mediante el paginador. Este paginador puede bien especificarse de uno de los diversos modos o bien se usará el predeterminado (ver opción -P para más detalles). Si no existe página cat, o si es más antigua que el fichero nroff, éste último es filtrado y presentando de forma inmediata.

Si se puede generar un fichero cat (existe un directorio cat relativo y tiene los permisos apropiados), %man% comprimirá y almacenará el fichero en segundo plano.

Los filtros son descifrados de diversos modos. Primeramente, se intenta usar el valor de la opción de la línea de órdenes -p o el contenido de la variable de entorno $MANROFFSEQ. Si no se ha usado -p ni tampoco se ha activado la variable de entorno, la primera línea del fichero en formato nroff es analizada en busca de una cadena de preprocesador. Para que esta línea contenga una cadena de preprocesador válida, su aspecto debe asemejarse a

'\" <cadena>

donde cadena puede ser cualquier combinación letras descritas para la opción -p más abajo.

Si ninguno de los métodos anteriores proporciona información de filtrado, se usa el conjunto predeterminado.

Se genera una tubería compuesta por los filtros y el formateador primario (nroff o [tg]roff con -t) y se ejecuta. Alternativamente, si existe en la raiz del árbol man, un programa ejecutable mandb_nfmt (o mandb_tfmt con -t) será éste el que se ejecute. Los argumentos que recibirá son la página de manual fuente, la cadena de preprocesador y, de forma opcional el dispositivo que se especifique mediante el argumento -T .

OPCIONES¶

La duplicación de opciones sin argumento tanto en la línea de órdenes, en $MANOPT, o en ámbos, no tiene ningún efecto dañino. Para aquellas opciones que requieren un argumento, cada duplicado sobreescribe el valor anterior del argumento.

-l, --local-file

Activa el modo `local'. Formatéa e imprime las páginas de manual locales en vez de buscarlas entre la colección de manuales del sistema. Cada página de manual argumento se supone fichero fuente en formato nroff. No se genera un fichero cat. Si se añade '-' a la lista de argumentos, se toma la entrada del stdin.

-L locales, --locale=locales

%man% normalmente determina su estado de locales actual mediante una llamada a la función de la biblioteca C setlocale(3) que interroga varias variables de entorno, entre otras $LC_MESSAGES y $LANG. Para sobreescribir temporalmente el valor determinado, puede usar esta opción y suplir la cadena de locales directamente a %man%. Es necesario notar que el cambio no tendrá lugar hasta que comience la búsqueda propiamente dicha. Salidas como el mensaje de ayuda siempre aparecen según los locales determinados inicialmente.

-D, --default

Esta opción se usa generalmente la primera y restaura el comportamiento de %man% al modo predeterminado. Se usa para restaurar las opciones modificadas mediante $MANOPT. Cualquier opción que siga a -D producirá el efecto usual.

-M ruta, --manpath=ruta

Especifica una ruta de manual alternativa. De forma predeterminada, %man% utiliza código derivado de %manpath% para determinar la ruta de búsqueda. Esta opción sobreescribe el valor de la variable de entorno $MANPATH y hace que la opción -m sea ignorada.

-P paginador, --pager=paginador

Especifica que paginador de salida se ha de usar. De forma predeterminada, %man% usa %pager%. Esta opción sobreescribe el valor de la variable de entorno $PAGER y no se puede usar a la vez que -f o -k.

-r prompt, --prompt=prompt

Si se usa una versión reciente del paginador less , %man% intentará fijar el prompt y alguna de sus opciones de forma inteligente. El prompt predeterminado será

 Página de Manual nombre(sección) línea x

donde nombre denota el nombre de la página de manual, sección denota la sección en la que se ha encontrado dicha página y x, el renglón actual. Esto se consigue usando la variable de entorno $LESS.

Si se suministra una cadena mediante la opción -r se sobreescribe este comportamiento predeterminado. La cadena puede contener el texto $MAN_PN que se convertirá en el nombre de la página de manual presentada y su sección rodeada de `(' y `)'. Así, la cadena que produce el comportamiento predeterminado se podría expresar como

\ Página\ de\nual\ \$MAN_PN\ ?ltlínea\ %lt?L/%L.:
byte\ %bB?s/%s..?\ (END):?pB %pB\\%..

La cadena se presenta en dos líneas para facilitar su lectura sólamente. Para entender su significado por favor vea la página de manual de less(1). La cadena de prompt es evaluada primero por la shell. Todas las dobles comillas comillas invertidas y barras invertidas del prompt deben ser precedidas de `\'. Si se termina la cadena de prompt con `\$', se podrán añadir posteriormente más opciones de less. De forma predeterminada %man% usa las opciones -ix8 .

-7, --ascii

Si está viendo una página de manual en código ascii(7) puro o en una terminal o emulador de terminal de 7 bits, algunos caracteres puede que no se impriman correctamente si usa el descriptor de dispositivo latin1(7) con GNU nroff. Esta opción permite que las páginas en puro ascii puedan ser presentadas en ascii en un dispositivo latin1 . No traducira ningún texto en latin1 . La siguiente tabla explica las traducciones que se realizan.

Descripción	Octal	latin1	ascii
guión de continuación	255	‐	-
marcador (punto medio)	267	•	o
acento agudo	264	´	'
signo de multiplicar	327	×	x

Si la columna de latin1 se imprime correctamente, su terminal puede ser usada con el conjunto latin1 de caracteres y esta opción no es necesaria. Si las columnas latin1 y ascii son idénticas, está leyendo la página usando esta opción o bien %man% no ha formateado la página usando la descripción de dispositivo latin1 . Si la columna latin1 no existe o está mal impresa, es posible que necesite esta opción.

Esta opción es ignorada cuando se usa a la vez que -t, -T o -Z y puede ser completamente inútil si el nroff usado es distinto del de GNU.

-S lista, --sections=lista

Lista es un compendio de secciones separadas por "dos puntos" que determina el orden en el que se consultan las secciones del manual. Esta opción sobreescribe el valor de la variable de entorno $MANSECT.

-a, --all

Por defecto, %man% termina después de presentar la página de manual que considera más apropiada de entre las encontradas. Si usa esta opción, forzará a %man% a presentar todas las páginas de manual cuyos nombres respondan a los criterios de la búsqueda.

-c, --catman

Esta opción no es de uso general y debería ser usada únicamente por el programa %catman% .

-d, --debug

En vez de presentar páginas de manual, imprime información de depurado.

-e sub-extensión, --extension=sub-extensión

Algunos sistemas como por ejemplo el paquete Tcl incorporan grandes paquetes de páginas de manual a la jerarquía principal. Para evitar tener dos páginas con un mismo nombre como por ejemplo exit(3), las páginas de Tcl han sido por lo general asignadas a la sección l. Esta solución es desafortunada y actualmente es posible poner las páginas en la sección correcta y asignarles una `extensión' específica, en este caso, exit(3tcl). En condiciones normales, %man% preferirá presentar exit(3) a exit(3tcl). Para solventar esta situación y evitar tener que saber a que sección pertenece la páguina requerida, es posible darle a %man% una extensión sub-extension indicando a que paquete tiene que pertenecer dicha página. Así con el ejemplo anterior, basta suministrar la opción -e tcl a %man% para que se restrinja la búsqueda a páginas que tengan *tcl como extensión.

-f, --whatis

Es equivalente a %whatis%. Presenta una breve descripción tomada de la página de manual cuando ésta está disponible. Véase %whatis%(1) para más detalles.

-h, --help

Imprime un mensaje de ayuda y termina.

-k, --apropos

Es equivalente a %apropos%. Realiza una busqueda de palabras clave entre las descripciones breves de las páginas de manual y presenta las páginas identificadas. Véase %apropos%(1) para más detalles.

-m sistema[,...], --systems=sistema[,...]

-p cadena, --preprocessor=cadena

Especifica la secuencia de preprocesadores a ejecutar antes de nroff o troff/groff. No todas las instalaciones tienen el conjunto completo de preprocesadores. Algunos de los preprocesadores y de las letras usadas para designarlos son: eqn (e), grap (g), pic (p), tbl (t), vgrind (v), refer (r). El valor de esta opción sobreescribe al contenido de la variable del entorno $MANROFFSEQ. %zsoelim% es ejecutado siempre en primer lugar.

-u, --update

Los cachés de los índices de las bases de datos son acutalizados `sobre la marcha', es decir, no es necesario que %mandb% se ejecute periódicamente para mantener la consistencia. Si la página que busca no se encuentra en los cachés o si se emplea la opción -a , %man% automáticamente comprobará la consistencia de los directorios para asegurar que los cachés son una representación fiel del sistema de ficheros. Para forzar una comprobación de consistencia de los `inodos' anterior a la búsqueda, use la opción -u.

-t, --troff

Usa %troff% para formatear las páginas de manual y escribirlas en el stdout. Esta opción es innecesaria en conjunción con -T o -Z.

-T dispositivo, --troff-device [=dispositivo]

-Z, --ditroff

groff ejecuta troff y usa un post-procesador para generar la salida apropiada para el dispositivo seleccionado. Si %troff% es groff, esta opción se pasa a groff evitando el uso de un post-procesador. Implica la opción -t.

-w, --where, --location

En vez de imprimir las páginas de manual, sólo imprime el/los lugar(es) en los que se encuentran los ficheros que serían formateados o impresos. Si se trata de un fichero cat, se imprime también la situación del fichero fuente nroff.

-V, --version

Imprime la versión y el autor.

ESTADO DE SALIDA¶

0

La ejecución del programa ha terminado con éxito.

1

Error de uso, sintaxis o del fichero de configuración.

2

Error operacional.

3

Un proceso hijo ha terminado con estatus no-nulo.

16

Al menos una de las/los páginas/ficheros/palabras clave no existe o no ha producido ninguna identificación positiva.

ENTORNO¶

MANPATH

Si se activa $MANPATH, su valor determina cual es la ruta de búsqueda para las páginas del manual.

MANROFFSEQ

Si se activa $MANROFFSEQ, su valor determina el conjunto de preprocesadores que filtran cada página de manual. La lista predeterminada de preprocesadores depende del sistema.

MANSECT

Si se activa $MANSECT, su valor es una lista de secciones delimitadas por "dos puntos" que permite determinar qué secciones de manual se usan en la búsqueda y en qué orden.

PAGER

Si se activa $PAGER, su valor determina el nombre del programa usado para presentar la página de manual. El sistema, de forma predeterminada, usará %pager% .

SYSTEM

Si se activa $SYSTEM, tiene el mismo efecto que la opción -m cadena donde cadena es el contenido de la variable $SYSTEM.

MANOPT

Si se activa $MANOPT, se analiza antes que la línea de órdenes de %man% , suponiéndose que el formato es similar. Como quiera que todas las demás variables de entorno específicas de %man% pueden expresarse como argumentos de la línea de órdenes y pueden por tanto ser incluidas en $MANOPT, se espera que se vuelvan obsoletas. N.B.: Todos los espacios que formen parte del argumento de una opción deben ir precedidos de `´.

LANG, LC_MESSAGES

Dependiendo del sistema y la implementación, una o ambas $LANG y $LC_MESSAGES son usadas para determinar los mensajes locales que se van a usar. %man% imprime los mensajes en dichos locales (si están disponibles). Veáse setlocale(3) para más detalles.

FICHEROS¶

%manpath_config_file%

fichero de configuración de man-db.

/usr/man

Una jerarquía global de páginas de manual

/usr/man/index.(bt|db|dir|pag)

Caché de índice de base de datos global tradicional.

/var/catman/index.(bt|db|dir|pag)

Caché del Índice de base de datos alternativo o conforme al FSSTND.

/usr/man/mandb_nfmt

Ejemplo de un guión opcional nroff de formateo por jerarquía.

/usr/man/mandb_tfmt

Ejemplo de un guión opcional [tg]roff de formateo por jerarquía para usar con -t.

VÉASE TAMBIÉN¶

%mandb%(8), %manpath%(1), manpath(5), %apropos%(1), %whatis%(1), %catman%(8), less(1), nroff(1), troff(1), groff(1), %zsoelim%(1), setlocale(3), man(7), ascii(7), latin1(7), FSSTND.

HISTORIA¶

1990, 1991 - Escrito originalmente por John W. Eaton (jwe@che.utexas.edu).

23 de Diciembre de 1992: Rik Faith (faith@cs.unc.edu) subsanó unos errores mediante las correcciones proporcionadas por Willem Kasdorp (wkasdo@nikhefk.nikef.nl).

30 de Abril de 1994 - 23 de Febrero de 2000: Wilf. (G.Wilford@ee.surrey.ac.uk) ha ido desarrollando y manteniendo este paquete con la ayuda de algunas personas con gran dedicación.

Traducción realizada por Luis F. González (luisgh@cogs.susx.ac.uk)